Lisp Machine Manual 1 Introduction 

1. Introduction 

1.1 General Information 

The Lisp Machine is a new computer system designed to provide a high-performance and 
economical implementation of the Lisp language. It is a personal computation system, which 
means that processors and main memories arc not time-multiplexed: when using a Lisp Machine, 
you get your own processor and memory system for the duration of the session. It is designed 
this way to relieve the problems of the running of large Lisp programs on time-sharing systems. 
Everything on the Lisp Machine is written in Lisp, including all system programs; there is never 
any need to program in machine language. The system is highly interactive. 

The Lisp Machine executes a new dialect of Lisp called Zetalisp, developed at the M.I.T. 
Artificial Intelligence Laboratory for use in artificial intelligence research and related fields. It is 
closely related to the Maclisp dialect, and attempts to maintain a good degree of compatibility 
with Maclisp, while also providing many improvements and new features. Maclisp, in turn, is 
based on Lisp 1.5. 

This document is the reference manual for the Zetalisp language. This document is not a 
tutorial, and it sometimes refers to functions and concepts that arc not explained until later in the 
manual. It is assumed that you have a basic working knowledge of some Lisp dialect; you will 
be able to figure out the rest of the language from this manual. 

There are also facilities explained in this manual that are not really part of the Lisp language. 
Some of these are subroutine packages of general use, and others are tools used in writing 
programs. The Lisp Machine window system and the major utility programs are not documented 
here. 

1.2 Structure of the Manual 

The manual starts out with an explanation of the language. Chapter 2 explains the different 
primitive types of Lisp object and presents some basic predicate functions for testing types. 
Chapter 3 explains the process of evaluation, which is the heart of the Lisp language. Chapter 4 
introduces the basic Lisp control structures. 

The next several chapters explain the details of the various primitive data-types of the 
language and the functions that deal with them. Chapter 5 deals with conses and the higher-level 
structures that can be built out of them, such as trees, lists, association lists, and property lists. 
Chapter 6 deals with symbols, chapter 7 with the various kinds of numbers, and chapter 8 with 
arrays. Chapter 9 explains character strings, which are a special kind of array. 

After this there are some chapters that explain more about functions, function-calling, and 
related matters. Chapter 10 presents all the kinds of functions in the language, explains function- 
specs, and tells how to manipulate definitions of functions. Chapters 11 and 12 discuss closures 
and stack-groups, two facilities useful for creating coroutines and other advanced control and 
access structures. 
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Next, a few lower-level issues are dealt with. Chapter 13 explains locatives, which are a kind 
of pointer to memory cells. Chapter 14 explains the "subprimitivc" functions, which are primarily 
useful for implementation of the Lisp language itself and the Lisp Machine's "operating system". 
Chapter 15 discusses areas, which give you control over storage allocation and locality of 
reference. 

Chapter 16 discusses the Lisp compiler, which converts Lisp programs into "machine 
language". Chapter 17 explains the I, isp macro facility, which allows users to write their own 
extensions to Lisp, extending both the interpreter and the compiler. The next two chapters go 
into detail about two such extensions, one that provides a powerful iteration control structure 
(chapter 18), and one that provides a powerful data structure facility (chapter 19). 

Chapter 20 documents flavors, a language facility to provide generic functions using the 
paradigm used in Smalltalk and the Actor families of languages, called "object-oriented 
programming" or "message passing". Flavors are widely used by the system programs of the Lisp 
Machine, as well as being available to the user as a language feature. 

Chapter 21 explains the Lisp Machine's Input/Output system, including streams and the 
printed representation of Lisp objects. Chapter 22 documents how to deal with pathnames (the 
names of files). Chapter 23 describes the use of the chaosnet. 

Chapter 24 describes the package system, which allows many name spaces within a single Lisp 
environment. Chapter 25 documents the "system" facility, which helps you create and maintain 
programs that reside in many files. 

Chapter 26 discusses the facilities for multiple processes and how to write programs that use 
concurrent computation. Chapter 27 explains how exceptional conditions (errors) can be handled 
by programs, handled by users, and debugged. Chapter 28 explains the instruction set of the 
Lisp Machine and tells you how to examine the output of the compiler. Chapter 29 documents 
some functions for querying the user, chapter 31 explains some functions for manipulating dates 
and times, and chapter 32 contains other miscellaneous functions and facilities. 

1.3 Notational Conventions and Helpful Notes 

There are several conventions of notation and various points that should be understood before 
reading the manual. JTiis section explains those conventions. 

The symbol " = >" will be used to indicate evaluation in examples. Thus, when you see "foo 
= > nil", this means the same thing as "the result of evaluating foo is (or would have been) nil". 

The symbol "==>" will be used to indicate macro expansion in examples. This, when you 
see "(foo bar) = => (aref bar 0)", this means the same thing as "the result of macro-expanding 
(foo bar) is (or would have been) (aref bar 0)". 

A typical description of a Lisp function looks like this: 
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fund ion -name argl argl &optional arg3 (arg4 (foo 3)) 

The function -name function adds together argl and argl, and then multiplies the result 
by arg3. If arg3 is not provided, the multiplication isn't done, function -name then 
returns a list whose first clement is this result and whose second clement is arg4. 
Examples: 

(function-name 3 4) => (7 4) 

(function-name 12 2 'bar) => (6 bar) 

Note the use of fonts (typefaces). The name of the function is in bold-face in the first line of 
the description, and the arguments are in italics. Within the text, printed representations of Lisp 
objects are in a different bold-face font, such as (+ foo 56), and argument references are 
italicized, such as argl and argl. A different, fixed-width font, such as function-name, is 
used for Lisp examples that are set off from the text. Other font conventions are that filenames 
are in bold-face, all upper case (as in SYS: SYS; SYSDCL LISP) while keys on the keyboard 
are in bold-face and capitalized (as in Help, Return and Meta). 

"Car", "cdr" and "cons" are in bold- face when the actual Lisp objects are being mentioned, 
but in the normal text font when used as words. 

The word "&optional" in the list of arguments tells you that all of the arguments past this 
point are optional. The default value can be specified explicitly, as with arg4 whose default value 
is the result of evaluating the form (foo 3). If no default value is specified, it is the symbol nil. 
This syntax is used in lambda-lists in the language, which are explained in section 3.2, page 21. 
Argument lists may also contain "&rest'\ which is part of the same syntax. 

The descriptions of special forms and macros look like this: 

do-three- times form Special Form 

This evaluates form three times and returns the result of the third evaluation. 

with-foo-bound-to-nil form... Macro 

This evaluates the forms with the symbol foo bound to nil. It expands as follows: 
(with-foo-bound-to-nil 
forml 

form! ...) ==> 
(let ((foo nil)) 
forml 
forml . . . ) 

Since special forms and macros are the mechanism by which the syntax of Lisp is extended, 
their descriptions must describe both their syntax and their semantics; functions follow a simple 
consistent set of rules, but each special form is idiosyncratic. The syntax is displayed on the first 
line of the description using the following conventions. Italicized words are names of parts of the 
form which are referred to in the descriptive text. They are not arguments, even though they 
resemble the italicized words in the first line of a function description. Parentheses ("( )") stand 
for themselves. Square brackets ("[]") indicate that what they enclose is optional. Ellipses ("...") 
indicate that the subform (italicized word or parenthesized list) which precedes them may be 
repeated any number of times (possibly no times at all). Curly brackets followed by ellipses 
("{}...") indicate that what they enclose may be repeated any number of times. Thus the first 
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line of the description of a special form is a "template" for what an instance of that special form 
would look like, with the surrounding parcntiiescs removed. The syntax of some special forms is 
sufficiently complicated that it docs not fit comfortably into this style; the first line of the 
description of such a special form contains only the name, and the syntax is given by example in 
the body of die description. 

'Hie semantics of a special form includes not only what it "docs for a living", but also which 
subforms are evaluated and what the returned value is. Usually this will be clarified with one or 
more examples. 

A convention used by many special forms is that all of their subforms after die first few are 

described as "body...". This means that the remaining subforms constitute the "body" of this 

special form; they are Lisp forms which are evaluated one after another in some environment 
established by the special form. 

This ridiculous special form exhibits all of the syntactic features: 

twiddle-frob [{frob option...)] {parameter value}... Special Form 

This twiddles the parameters of frob, which defaults to default-frob if not specified. 
Each parameter is the name of one of the adjustable parameters of a frob; each value is 
what value to set that parameter to. Any number of parameter/value pairs may be 
specified. If any options are specified, they are keywords which select which safety checks 
to override while twiddling the parameters. If neither frob nor any options are specified, 
the list of them may be omitted and the form may begin directly with the first parameter 
name. 

frob and the values are evaluated; the parameters and options are syntactic keywords and 
not evaluated. The returned value is the frob whose parameters were adjusted. An error 
is signalled if any safety checks are violated. 

Operations, the message-passing equivalent of ordinary Lisp's functions, are described in this 
style: 

: operation- name argl org! &optional arg3 Operation on flavor- name 

This is the documentation of the effect of performing operation :operation-name (or, 
sending a message named :operation-name), with arguments argl, arg2, and arg3, on 
an instance of flavor flavor-name. 

Descriptions of variables ("special" or "global" variables) look like this: 

typical -variable Variable 

The variable typical -variable has a typical value.... 

Most numbers shown are in octal radix (base eight). Spelled out numbers and numbers 
followed by a decimal point are in decimal. This is because, by default, Zetalisp types out 
numbers in base 8; don't be surprised by this. If you wish to change it, see the documentation 
on the variables ibase and base (page 371). 
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All uses of the phrase "Lisp reader", unless further qualified, refer to the part of Lisp which 
reads characters from I/O streams (the read function), and not the person reading this manual. 

There are several terms which are used widely in other references on Lisp, but are not used 
much in this document since they have become largely obsolete and misleading. For the benefit 
of those who may have seen them before, they are: "s-expression", which means a Lisp object; 
"dotted pair", which means a cons; and "atom", which means, roughly, symbols and numbers 
and sometimes other things, but not corises. The terms "list" and "tree" arc defined in chapter 5, 
page 60. 

The characters acute accent ( ' ) (also called "single quote") and semicolon ( ; ) have special 
meanings when typed to Lisp; they are examples of what are called macro characters. Though 
the mechanism of macro characters is not of immediate interest to the new user, it is important to 
understand the effect of these two, which are used in the examples. 

When the Lisp reader encounters a " ' ", it reads in the next Lisp object and encloses it in a 
quote special form. That is, 'foo-symbol turns into (quote foo-symbol), and '(cons 'a 'b) 
turns into (quote (cons (quote a) (quote b))). The reason for this is that "quote" would 
otherwise have to be typed in very frequently, and would look ugly. 

The semicolon is used as a commenting character. When the Lisp reader sees one, the 
remainder of the line is discarded. 

The character "/" is used for quoting strange characters so that they are not interpreted in 
their usual way by the Lisp reader, but rather are treated the way normal alphabetic characters 
are treated. So, for example, in order to give a "/" to the reader, you must type "//", the first 
"/" quoting the second one. When a character is preceded by a "/" it is said to be slashified. 
Slashifying also turns off the effects of macro characters such as " ' " and ";". 

The following characters also have special meanings and may not be used in symbols without 
slashification. These characters are explained in detail in the section on printed representation 
(section 21.2.2, page 371). 

Double-quote delimits character strings. 
# Number-sign introduces miscellaneous reader macros. 
Backquote is used to construct list structure. 
Comma is used in conjunction with backquote. 
: Colon is the package prefix. 

| Characters between pairs of vertical-bars are quoted. 

9 Circle-cross lets you type in characters using their octal codes. 

All Lisp code in this manual is written in lower case. In fact, the reader turns all symbols 
into upper-case, and consequently everything prints out in upper case. You may write programs 
in whichever case you prefer. 
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You will see various symbols that have the colon (:) character in their names. By convention, 
all "keyword" symbols in the Lisp Machine system have names starting with a colon. The colon 
character is not actually part of the print name, but is a package prefix indicating that the symbol 
belongs to the package with a null name, which means the user package. So, when you print 
such a symbol, you won't see the colon if the current package is user. However, you should 
always type in the colons where the manual tells you to. This is all explained in chapter 24; 
until you read that, just make believe that the colons are part of the names of the symbols, and 
don't worry that they sometimes don't get printed out for keyword symbols. 

This manual documents a number of internal functions and variables, which can be identified 
by the "si:" prefix in their names. The "si" stands for "system internals". These functions and 
variables are documented here because they are tilings you sometimes need to know about. 
However, they are considered internal to the system and their behavior is not as guaranteed as 
that of everything else. They may be changed in the future. 

Zetalisp is descended from Maclisp, and a good deal of effort was expended to try to allow 
Maclisp programs to run in Zetalisp. Throughout the manual, there are notes about differences 
between the dialects. For the new user, it is important to note that many functions herein exist 
solely for Maclisp compatibility; they should not be used in new programs. Such functions are 
clearly marked in the text. 

The Lisp Machine character set is not quite the same as that used on I.T.S. nor on Multics; 
it is described in full detail elsewhere in the manual. The important thing to note for now is that 
the character "newline" is the same as Return, and is represented by the number 215 octal. (This 
number should not be built into any programs.) 

When the text speaks of "typing Control -Q" (for example), this means to hold down the 
Control key on the keyboard (cither of die two keys labeled "CTRL"), and, while holding it 
down, to strike the Q key. Similarly, to type Meta-P, hold down either of the Meta keys and 
strike P. To type Control- Meta -T hold down both Control and Meta. Unlike ASCII, the Lisp 
machine character set has no "control characters"; Control and Meta (and Super and Hyper) are 
modifiers that can be added to a character of keyboard input. These modifier bits are not present 
in characters in strings or files. 

Many of the functions refer to "areas". The area feature is only of interest to writers of large 
systems and can be safely disregarded by the casual user. It is described in chapter 15. 
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